前言

入職接近一個月要準備接手專案的部分，
可能會從一個舊的框架系統，要改成前後端分離，
將後端分成Restful API的方式進行，
因此這篇整理一下Restful API的觀念。

Restful API

RESTful API，
全名為Representational State Transfer Application Programming Interface，
是一種設計風格，用於簡化網路應用程序之間的通信。
它基於HTTP協議，並使用URL來定位資源，通常使用JSON或XML格式來傳輸數據。
RESTful API已經成為當今網路應用程序的標準，因此學習它對於開發現代軟體應用程序至關重要。

基本概念

RESTful API的核心概念之一是資源（Resource）。
資源可以是任何具體或抽象的實體，例如用戶、產品、訂單或文件。
每個資源都有一個唯一的URL（Uniform Resource Locator）用於定位和訪問它。
例如，一個用於獲取特定用戶資訊的URL可能如下所示：

https://example.com/api/users/123

上面的URL指向一個用戶資源，其中123是該用戶的唯一識別碼。

另一個重要的概念是狀態（State）。
資源的狀態指的是資源的當前信息或數據。
RESTful API使用HTTP方法來執行不同的操作，這些操作可以改變資源的狀態。
例如，使用GET方法可以獲取資源的狀態，而使用POST方法可以創建新的資源。

設計原則

要設計出良好的RESTful API，需要遵循一些設計原則：

1. 使用合適的HTTP方法： 使用HTTP方法來表示操作類型，例如GET用於獲取資源，POST用於創建資源，PUT用於更新資源，DELETE用於刪除資源。

2. 使用清晰的URL： URL應該具有可讀性，並且應該反映資源的層次結構。避免使用過多的嵌套。

3. 使用名詞而不是動詞： URL中應該包含資源名稱，而不是動詞。例如，使用/users表示用戶資源，而不是/getUsers。

4. 支援多種數據格式： RESTful API應該支援多種數據格式，如JSON和XML，以滿足不同客戶端的需求。

5. 使用狀態碼： 使用HTTP狀態碼來表示操作的結果，例如200 OK表示成功，404 Not Found表示資源不存在。

HTTP方法

HTTP方法是RESTful API中的重要部分，它們指定了對資源的不同操作。以下是常用的HTTP方法：

• GET： 用於獲取資源的狀態或數據。不應該對資源進行更改。

• POST： 用於創建新資源。通常用於提交表單或上傳文件。

• PUT： 用於更新現有資源。通常用於全量更新，即用新資料完全替換現有資源。

• PATCH： 用於部分更新現有資源。通常用於只更新部分資料。

• DELETE： 用於刪除資源。從伺服器中移除資源。

狀態碼

HTTP狀態碼是用於表示伺服器對請求的回應的三位數碼。RESTful API使用狀態碼來傳達操作的結果。以下是一些常見的HTTP狀態碼：

• 200 OK： 請求成功，伺服器返回數據。

• 201 Created： 資源成功創建，通常在使用POST方法創建資源時返回。

• 204 No Content： 請求成功，但伺服器不返回內容，通常在使用DELETE方法刪除資源時返回。

• 400 Bad Request： 請求無效，通常由客戶端引起。

• 401 Unauthorized： 未經授權，需要驗證。

• 404 Not Found： 資源未找到。

• 500 Internal Server Error： 伺服器內部錯誤。

身分驗證

保護RESTful API免受未經授權的訪問是至關重要的。
身分驗證（Authentication）是一個常見的安全機制，用於確保只有授權的用戶能夠訪問資源。
常見的身分驗證方式包括基本身分驗證（Basic Authentication）、
令牌身分驗證（Token Authentication）和OAuth等。

版本控制

當API發生變更時，維護現有客戶端的相容性是一個挑戰。
為了解決這個問題，可以使用API版本控制。
通常，版本號會包含在URL中，以區分不同的API版本。例如：

https://example.com/api/v1/users

這樣可以讓新版本的API與舊版本並存，並允許客戶端在過渡期間選擇使用哪個版本。

最佳實踐

學習RESTful API的最佳方式之一是閱讀和理解優秀的API文檔，
如GitHub、Twitter和Google Maps等知名服務的API文檔。
此外，使用工具來測試和測試API，例如Postman或Swagger。

另一個重要的最佳實踐是保持API的簡潔性和一致性。
選擇有意義的URL、使用適當的HTTP方法、提供清晰的狀態碼和錯誤消息，並遵循RESTful設計原則。

結語

這篇筆記提供了一個深入的了解RESTful API的基本概念、
設計原則、HTTP方法、狀態碼、身分驗證、版本控制和最佳實踐等重要主題。
RESTful API已經成為現代軟體開發的重要組件，
無論是後端開發者、前端工程師，
掌握RESTful API的知識和技能都是很重要的一環。
希望這份學習筆記能幫助你更好地理解和應用RESTful API。
下一篇再來介紹前後端分離。